User Linking in UPS

We can map alternate user IDs to existing user profile data through uploading a file that maps IDs.

Use Cases

  • Migration Efforts: When migrating to a new platform, leverage existing user profiles for personalization by mapping new user IDs to the old user IDs.

  • Different Systems across Different Channels: When the user IDs passed to Algonomy are not consistent across different channels, leverage the collected data across those user IDs for personalizing the experience across all channels.

For the clients of UPS (Algonomy Applications and Profiles API), the merge of multiple profiles is completely transparent and seamless. When querying the primary user ID, the response given by UPS is the merged data from all the profiles linked to the requested primary user ID.

  • The linking of profiles is dependent on the User Link mapping and will only be as clean as the mapping file is.

  • The more profiles that a request must load to personalize the response increases the latency of the response. Limit the number of IDs that a single user ID is linked to.

With a simple mapping file where you tell us which profiles should be linked together, UPS can stitch together the user information from multiple profiles in a coherent and chronological fashion to give you the complete picture of your customer.

Merged Profiles

Some points to note about the response of merged profiles

  • The response will still be truncated to meet the profile cut-off of a single response.

    For example, if User A=UserB, and each has a history of 15 item views, when you request for profile data for User A, you will still get a total of 15 items view. However, those 15 item views will be the 15 most recent item views of User A and User B combined and sorted by time. 

Note: UPS keeps up to 15 item views and 50 purchases.

  • User data that is added to the profiles using the batch update process is not merged in the response (as that data is not in the form of an "event"). Rather data for each linked profile is shown individually.

  • The mapping file is not incremental. Each time a new file is uploaded, it replaces any user mapping data previously uploaded.

  • A maximum of 10 profiles can be merged. This is to keep response times reasonable.

Requirements

Contact your account manager or project manager to enable user linking for your site and to get credentials for uploading the mapping file.

User Link Mapping

The user link mapping file is a simple flat file that gives the mapping of the profiles to merge and is loaded into our platform via the build-ftp server. The data is provided as text file with IDs separated by CTRL-A. Each new line should start with the primary user ID, followed by all the profiles to be linked to that primary user ID using CTRL-A as a separator. For a typical example where each primary user ID is explicitly identified, it would look something like the following.

UserA ^A UserB ^A User135

User246 ^A UserC ^A User890

The above two lines indicate that (assuming explicit mapping, see below)

UserA = UserB ; User135

User246 = UserC ; User890

 

    Notes:
  • We support delta feed for user linking. For more information about delta feed, see Batch Delta Feed File Upload in Omnichannel Personalization Feeds Guide.
  • If IDs are separated by "^A" (string), then the processing will fail.  To successfully link the userIds, CTRL-A (Control Character) must be used. For more information, refer  https://en.wikipedia.org/wiki/Control_character.

Supported Mapping Formats

There are two user link mapping formats defined.

Explicit Mapping

This is where the user links are uni-directional. UserA = UserB does not automatically mean UserB = UserA.  This is also the default mapping format.

The data maps from the FIRST entry on each line to all the other IDs on the line. For example, a simple user link mapping file would be a flat text file with contents similar to this: 

userA ^A userB

userB ^A userC ^A userD

This is telling the User Profile Service that

userA <= userB

userB <= userC ; userD

When the user asks for data on userA he will receive the profile consisting of the merged data of userA and userB.

When the user asks for data on userB he will receive the profile consisting of the merged data of userB, userC and userD.

Notice that the mapping is one-directional, so querying for userC will NOT include the data for userB.

Grouped Mapping

This is bi-directional mapping. For each line in the mapping file, the data for each of the IDs map to all the other IDs. There is a command line option of "-linktype grouped" that can be used to tell UPS of this mapping format. If any of the IDs on the line appear on another line, the sets will be merged, and all IDs of the merged set will map to all the other IDs.

To illustrate, assume the data file looks like this:

userA ^A userB

userC ^A userD ^A userE

userF ^A userA

If the "-linktype grouped" is used, the UPS will interpret this as

userA <=> userB <=> userF.

userC <=> userD <=> userE

Loading the User Link Mapping File:

ftp build-ftp.richrelevance.com 2222

// Log in as user/pwd

put ~/userlinkexp.txt userlinkexp.txt

site upslink userlinkexp.txt -linktype explicit

Valid link types are 'explicit' and 'grouped' with 'explicit' being the default.

Refer the example User Link File - userlinkexp.txt.

Note: With User Profile Enrichment Service API, it is possible to upload/update the User Linking information in near real-time. For more information about the User Profile Enrichment Service API, see User Profile Enrichment Service.

Service Limits

  • Currently, a maximum of 10 million records are supported in one file.
  • With each user having 5-6 user mappings.
  • With explicit mapping, uploading 10 million records takes about 5-10 minutes.
  • With grouped mapping, uploading 10 million records takes about 30-60 minutes.
  • Across all user linkings, segments, and attributes across all customers, a maximum of 5 concurrent requests are allowed. Rest of the requests wait in the job queue.

If the job queue is full, the following message is displayed. The timer starts only after this message disappears:

"Request is in the queue. File processing will begin shortly…"

If the request is picked up by the UPS user linking process (UPS FTP service), the following message is displayed:

"Processing Linking file..."

Note: If the request is in the job queue, then the SLA might increase depending on the wait time. During these scenarios, it does not meet the above-mentioned timings.

Considerations for User Linking

UPS is designed to return provisional data (anonymous events) only for primary users and not for alternate users. Whatever user is used in the query in the path parameter, only for that user, provisional data is returned by UPS Reader. For the alternate user, UPS only returns events that have the user ID in it. For those users that have anonymous data associated, you will see a small set of mismatch when you query with alternate users.

Will the anonymous data be linked to alternate user?

Yes. But it does not happen immediately. The anonymous data gets linked in the following two scenarios.

  • A process called UPS Compactor runs on a weekly basis that does the anonymous user linking. After the Compactor runs, the anonymous data will get migrated to the user table and therefore, those events will be visible in the UPS Reader response. This happens only if the events are above the threshold (default threshold is 15).

  • Even before Compactor runs, if the number of events crosses the threshold (default threshold is 15), the UPS Reader has a logic to trigger compaction and copy over the anonymous events to the user table. In such case, it will match as well. This is true for a relatively active user. UPS Reader also triggers compaction provided a request is fired to UPS Reader for that user.